vecfcn_helper Derived Type

type, public :: vecfcn_helper

Defines a type capable of encapsulating a system of nonlinear equations of the form: F(X) = 0. This type is used to establish the system of equations to solve, and provides a means for computing the Jacobian matrix for the system of equations, and any other ancillary operations that may be needed by the solver.


Components

Type Visibility Attributes Name Initial
real(kind=real64), public, allocatable, dimension(:) :: m_fwork

A function evaluation workspace array.

real(kind=real64), public, allocatable, dimension(:,:) :: m_jwork

An FD workspace for the Jacobian calculations with one column available per thread.

real(kind=real64), public, allocatable, dimension(:,:) :: m_xjwork

An FD workspace for the Jacobian calculations with one column available per thread.


Type-Bound Procedures

procedure, public :: fcn => vfh_fcn

  • private subroutine vfh_fcn(this, x, f, args)

    Executes the routine containing the system of equations to solve. No action is taken if the pointer to the subroutine has not been defined.

    Arguments

    Type IntentOptional Attributes Name
    class(vecfcn_helper), intent(inout) :: this

    The vecfcn_helper object.

    real(kind=real64), intent(in), dimension(:) :: x

    An N-element array containing the independent variables.

    real(kind=real64), intent(out), dimension(:) :: f

    An M-element array that, on output, contains the values of the M functions.

    class(*), intent(in), optional :: args

    An optional argument to allow the user to communicate with the routine.

procedure, public :: get_equation_count => vfh_get_nfcn

  • private function vfh_get_nfcn(this) result(n)

    Gets the number of equations in this system.

    Arguments

    Type IntentOptional Attributes Name
    class(vecfcn_helper), intent(in) :: this

    The vecfcn_helper object.

    Return Value integer

    The function count.

procedure, public :: get_thread_count => vfh_get_nthreads

  • private pure function vfh_get_nthreads(this) result(rst)

    Gets the maximum number of threads to use when evaluating the Jacobian matrix.

    Arguments

    Type IntentOptional Attributes Name
    class(vecfcn_helper), intent(in) :: this

    The vecfcn_helper object.

    Return Value integer

    The number of threads allowed.

procedure, public :: get_variable_count => vfh_get_nvar

  • private function vfh_get_nvar(this) result(n)

    Gets the number of variables in this system.

    Arguments

    Type IntentOptional Attributes Name
    class(vecfcn_helper), intent(in) :: this

    The vecfcn_helper object.

    Return Value integer

    The number of variables.

procedure, public :: is_fcn_defined => vfh_is_fcn_defined

  • private function vfh_is_fcn_defined(this) result(x)

    Tests if the pointer to the subroutine containing the system of equations to solve has been assigned.

    Arguments

    Type IntentOptional Attributes Name
    class(vecfcn_helper), intent(in) :: this

    The vecfcn_helper object.

    Return Value logical

    Returns true if the pointer has been assigned; else, false.

procedure, public :: is_jacobian_defined => vfh_is_jac_defined

  • private function vfh_is_jac_defined(this) result(x)

    Tests if the pointer to the Jacobian calculation routine has been defined.

    Arguments

    Type IntentOptional Attributes Name
    class(vecfcn_helper), intent(in) :: this

    The vecfcn_helper object.

    Return Value logical

    Returns true if the pointer has been assigned; else, false.

procedure, public :: jacobian => vfh_jac_fcn

  • private subroutine vfh_jac_fcn(this, x, jac, fv, args)

    Executes the routine containing the Jacobian matrix if supplied. Otherwise, uses AD when an AD-compatible function is registered, falling back to finite differences.

    Arguments

    Type IntentOptional Attributes Name
    class(vecfcn_helper), intent(inout) :: this

    The vecfcn_helper object.

    real(kind=real64), intent(inout), dimension(:) :: x

    An N-element array containing the independent variables defining the point about which the derivatives will be calculated.

    real(kind=real64), intent(out), dimension(:,:) :: jac

    An M-by-N matrix where, on output, the Jacobian will be written.

    real(kind=real64), intent(in), optional, dimension(:), target :: fv

    An optional M-element array containing the function values at x. If not supplied, the function values are computed at x.

    class(*), intent(in), optional :: args

    An optional argument to allow the user to communicate with the routine.

procedure, public :: set_auto_fcn => vfh_set_auto_fcn

  • private subroutine vfh_set_auto_fcn(this, fcn, nfcn, nvar)

    Establishes a pointer to the AD-compatible routine containing the function. If utilized, this will allow for computation of the gradient, for applicable solvers, via AD. However, a user-defined gradient does take precedence over an AD generated gradient.

    Arguments

    Type IntentOptional Attributes Name
    class(vecfcn_helper), intent(inout) :: this

    The vecfcn_helper object.

    procedure(vector_function), intent(in), pointer :: fcn

    The function pointer.

    integer, intent(in) :: nfcn

    The number of functions.

    integer, intent(in) :: nvar

    The number of variables.

procedure, public :: set_fcn => vfh_set_fcn

  • private subroutine vfh_set_fcn(this, fcn, nfcn, nvar)

    Establishes a pointer to the routine containing the system of equations to solve.

    Arguments

    Type IntentOptional Attributes Name
    class(vecfcn_helper), intent(inout) :: this

    The vecfcn_helper object.

    procedure(vecfcn), intent(in), pointer :: fcn

    The function pointer.

    integer, intent(in) :: nfcn

    The number of functions.

    integer, intent(in) :: nvar

    The number of variables.

procedure, public :: set_jacobian => vfh_set_jac

  • private subroutine vfh_set_jac(this, jac)

    Establishes a pointer to the routine for computing the Jacobian matrix of the system of equations. If no routine is defined, the Jacobian matrix will be computed numerically (this is the default state).

    Arguments

    Type IntentOptional Attributes Name
    class(vecfcn_helper), intent(inout) :: this

    The vecfcn_helper object.

    procedure(jacobianfcn), intent(in), pointer :: jac

    The function pointer.

procedure, public :: set_thread_count => vfh_set_nthreads

  • private subroutine vfh_set_nthreads(this, n)

    Sets the maximum number of threads to use when evaluating the Jacobian matrix. With multiple threads, function callbacks must be thread-safe. Do not evaluate the same helper concurrently from separate callers.

    Arguments

    Type IntentOptional Attributes Name
    class(vecfcn_helper), intent(inout) :: this

    The vecfcn_helper object.

    integer, intent(in) :: n

    The maximum allowed number of threads.